Do not reject settings calls when the settings file cannot be saved - #72

What was wrong

setWifiOnly() and updateHeaders() rejected E_STORAGE when the settings file could not be saved, for example on a full disk. The new value was then dropped for the whole session. In Diana, one such rejection at startup stopped every upload for the session (Sentry DIANA-3427 on iOS, DIANA-33NX for headers). The app should not have to handle this. The library should.

This PR is on top of #69.

What changes

On both platforms, a settings call now does these steps:

1. Check the input. An invalid header still rejects E_INVALID and changes nothing.
2. Apply the new value in memory. This session uses it at once: the Wi-Fi session pick, the pause gates, the new headers on queued entries, and the resume of entries in awaiting-auth.
3. Save the file. If the save fails, the call still resolves. The library logs a warning with the cause from Skip unchanged setWifiOnly writes and put the cause in E_STORAGE #69 and remembers that the file is behind. On Android the warning goes to Diag.warn, so takeDiagnostics() returns it. On iOS it goes to the device log (NSLog) only for now, once per run of failures, because iOS takeDiagnostics() returns an empty list. When the iOS diagnostics list from Report the v9 work left on the device in takeDiagnostics() #74 is in master, the one function reportSettingsSaveFailure can also record it there.
4. Save again while the file is behind: at the next settings call (also one that changes nothing), when the app becomes active, and when the app leaves the foreground. Leaving the foreground is the last chance before a relaunch with no JS. There is no timer.

These retries run only while the process lives. A new process does not know that the file was behind. It uses the last value that reached the disk. So the README now tells apps to send their settings again at each start. A call with an unchanged value writes nothing.

pause() and resume() changed too. They had the same failure, so they get the same change. There is no production evidence for them. The evidence is DIANA-3427 for setWifiOnly and DIANA-33NX for updateHeaders. If a pause save never lands and the app is relaunched, native reads the old pause state, and at launch it moves the entries to match it (iOS reconcile, Android boot sweep). So a paused entry can run until the app calls pause() again. The other direction is the same: if a resume() save never lands and the app is relaunched, the entries stay paused until JS calls resume() again.

Android entry saves. updateHeaders(), pause() and resume() also save each entry they change. iOS changes an entry in memory when its save fails (commit() never throws). Android cannot do that: workers and the boot sweep read entries from disk, and the store has no in-memory copy of an entry. Adding one would need a cache that every reader uses, and a crash could then lose a change. So on Android these three calls still reject E_STORAGE when an entry file cannot be saved. What changed is the order. transformAll now goes on past a failed entry. Each call stops or schedules every entry it did save, and only then rejects with the count and the cause. Before, the first failure stopped the loop, and entries already saved as queued got no WorkManager work until the next launch. An entry that failed keeps its old state: old headers and still parked for updateHeaders(), still paused for resume(). For pause(), its worker sees the paused gate before its next attempt. The README, JSDoc and CHANGELOG say this.

Android toResumed. It now compares parkedGeneration with the entry's own headerGeneration, not with the settings value. The settings value can be stale after a settings save that never landed. Before, resume() or the boot sweep could send an entry back to awaiting-auth although it held new headers it never tried.

configure() never rejected, but it shares the save code. It now also keeps its retry defaults in memory when the save fails. Before, it dropped them.

Header generation. The headers are saved in each entry, not in the settings file. So a lost settings save loses only the header generation number. If that number goes back after a relaunch, the next updateHeaders() can reuse it, and a 401 under the newest headers parks instead of sending again. iOS now raises the number at launch above every saved entry and every task-map tag. A tag can be higher than every entry, because taskWillBegin re-tags a task without saving its entry. Android has no task tags, so it raises the number above every entry at each updateHeaders().

Where to look

• iOS, ios/QueueCoordinator.swift: applySettings, retrySettingsSave, settingsBehind and reportSettingsSaveFailure replace saveSettings. Callers are configure, changeGate, setWifiOnly, updateHeaders, appBecameActive and appResignedActive. The generation fix is at the end of init, with TaskMap.maxHeaderGeneration.
• Android, QueueSettings.kt: QueueSettingsStore.update no longer throws for a failed write. saveIfBehind and isBehind are new. The warning goes to Diag.warn. Only the first failure in a row is persisted, so retries on a full disk do not fill the log.
• Android, UploaderModule.kt: the module is now a LifecycleEventListener. onHostResume and onHostPause call saveIfBehind on the queue executor.
• Android, QueueController.kt: transformAll and Transformed.throwIfFailed, used by pause, resume and updateHeaders. updateHeaders raises the generation above every entry's value.
• Android, EntryTransitions.toResumed: the entry's own generation.
• README, CHANGELOG, JSDoc in src/index.ts, comments in src/NativeRNFileUploader.ts. src/testing.ts did not change: its failNext() is generic and does not model these rejections.

Tested

• cd ios && swift test: 258 tests, 0 failures (245 on the base branch).
• Android ./gradlew :react-native-background-upload:testDebugUnitTest from example/RNBGUExample/android: 349 tests, 0 failures (337 on the base branch).
• yarn lint:ci and yarn typecheck pass. yarn test: 194 pass.

The new tests are in ios/Tests/SettingsSaveTests.swift, QueueSettingsTest.kt, QueueControllerTest.kt and EntryTransitionsTest.kt. They cover each call with a failed settings save, the retries, the header generation after a relaunch, a second failure in a row that is not persisted, and on Android an entry save that fails during updateHeaders, pause and resume. Three tests that expected the old rejection were removed.

Limits

• onHostResume and onHostPause are not covered by unit tests, because UploaderModule has none. The store method they call is covered.
• The iOS rule that logs only the first failure in a row has no test, because it changes only an NSLog call.
• The retry when the app leaves the foreground runs on the queue after the app resigns. iOS can suspend the app before it runs. There is no background task for it.

🤖 Generated with Claude Code